Sprite 1984 - 1993/Sprite 1984 - 1993.iso/src/cmds/mkmf.prog/RCS/mkmf.man,v

Text File | 1991-05-24 | 35.5 KB | 1,017 lines

head     1.11;
branch   ;
access   ;
symbols  ;
locks    ; strict;
comment  @@;


1.11
date     91.05.23.17.03.22;  author kupfer;  state Exp;
branches ;
next     1.10;

1.10
date     91.05.23.16.56.53;  author kupfer;  state Exp;
branches ;
next     1.9;

1.9
date     90.09.21.16.50.41;  author kupfer;  state Exp;
branches ;
next     1.8;

1.8
date     90.02.27.17.46.06;  author douglis;  state Exp;
branches ;
next     1.7;

1.7
date     89.05.22.12.30.14;  author jhh;  state Exp;
branches ;
next     1.6;

1.6
date     89.04.03.22.19.32;  author douglis;  state Exp;
branches ;
next     1.5;

1.5
date     89.04.03.22.17.47;  author douglis;  state Exp;
branches ;
next     1.4;

1.4
date     89.04.03.22.16.36;  author douglis;  state Exp;
branches ;
next     1.3;

1.3
date     88.12.30.09.56.12;  author ouster;  state Exp;
branches ;
next     1.2;

1.2
date     88.12.28.12.05.25;  author ouster;  state Exp;
branches ;
next     1.1;

1.1
date     88.12.28.11.43.58;  author ouster;  state Exp;
branches ;
next     ;


desc
@@


1.11
log
@Add a couple .LP's to separate main text from examples.
@
text
@' $Header: /sprite/src/cmds/mkmf.prog/RCS/mkmf.man,v 1.10 91/05/23 16:56:53 kupfer Exp Locker: kupfer $ SPRITE (Berkeley)
.so \*(]ltmac.sprite
.HS MKMF cmds
.BS
.SH NAME
mkmf \- generate Makefiles automatically
.SH SYNOPSIS
\fBmkmf\fR [\fB\-f \fImakefile\fR] [\fB\-x\fR] [\fB\-m \fImachineType\fR]
[\fB-m\fImachineType\fR]
.SH OPTIONS
.IP "\fB\-f \fImakefile\fR"
Generate a file named \fImakefile\fR
instead of \fBMakefile\fR.  Also use \fImakefile.\fBproto\fR,
\fImakefile.\fBed\fR, and \fImakefile\fR.\fBex\fR instead of
\fBMakefile.proto\fR etc.
.IP "\fB\-x\fR"
Turns on echo-ing so that all the commands in the \fBmkmf\fR scripts
are printed on the terminal.  This is useful primarily for
debugging \fBmkmf\fR scripts.
.IP "\fB\-m \fImachineType\fR or \fB-m\fImachineType\fR"
Work only on subdirectory for
\fImachineType\fR. Multiple \fB\-m\fR flags
can be used to run \fBmkmf\fR on multiple machine types.
.BE

.SH INTRODUCTION
.LP
\fBMkmf\fR generates a \fBMakefile\fR for the current working directory.  It
also creates additional make-related files in machine-dependent
subdirectories of the current directory.  \fBMkmf\fR can generate
\fBMakefile\fRs for a variety of directories, including those holding programs,
libraries, header libraries, kernel sources, and other things.
\fBmkmf\fR manages all of the directories holding Sprite system code.
In normal use, all you should have to do is type "mkmf";  \fBmkmf\fR
will generate a suitable \fBMakefile\fR based on the directory's full
path name and
the files and subdirectories in it.  After that you can invoke
\fBpmake\fR to recompile in the directory, install, and so on.  The files
produced by \fBmkmf\fR will only work with \fBpmake\fR, not with the original
UNIX version of \fBmake\fR (but in Sprite \fBmake\fR is a symbolic link to
\fBpmake\fR).  This man page assumes that you are familiar with \fBpmake\fR;  if
not, you should read the \fBpmake\fR tutorial.
.LP
Warning:  there is also a UNIX program called \fBmkmf\fR;  although its
general goal is the same as this program's, its mechanisms are very different.
.LP
Normally, you should re-run \fBmkmf\fR in a directory whenever you add or delete
source files.  When \fBmkmf\fR runs, it assumes that
all of the source files (those with extensions .c, .h, .y, etc.)
are to be used to create a single program or library, and it
generates \fBMakefile\fR accordingly.  If there are source files that
don't pertain to the thing being created (e.g. test programs),
put them in a subdirectory where \fBmkmf\fR won't see them.

.SH "MAKEFILE STRUCTURE"
.LP
The makefile structure that \fBmkmf\fR generates is a bit complicated,
but it's also powerful and flexible.  Among other things, it supports
compilation for multiple target machines from a single set of source
files, and it makes it easy to make a global change in the way all
directories of a particular type are made (e.g. all command programs, or all
libraries).  For most directories
there are five kinds of \fBpmake\fR-related files:
.IP "\fBMakefile\fP"
This is the main file generated by \fBmkmf\fR, but it is short and
does relatively little.  It sets up several \fBpmake\fR
variables that give the name of the program, a list of target machines
for which the program can be compiled, default flags for C compilation,
and so on.  Then \fBMakefile\fR includes the other files described below,
which contain most of the useful \fBpmake\fR-related information.
\fBMakefile\fR contains information that may be different for this
directory than for other directories of the same type (for example, each
library has a different
name), but it only contains information that is independent of the particular
target machine being compiled for.
.IP "\fB*.md/md.mk\fP"
There is one subdirectory for each target machine that this program
or library or module can be compiled to run on.  These are called
\fImachine-dependent subdirectories\fR and have names \fIx\fB.md where
\fIx\fR is the type of the target machine, e.g., \fBsun2.md\fR
or \fBsun3.md\fR.  A machine-dependent subdirectory holds all
information that is different for that particular machine than for
other machines.  This includes the object files compiled for that
machine, plus any machine-dependent sources.  Most user programs don't have
machine-dependent sources, but many of the kernel modules and
libraries do.  In each machine-dependent subdirectory there is a
file \fBmd.mk\fR, generated automatically by \fBmkmf\fR.
\fBMd.mk\fR is included by \fBMakefile\fR and
creates variables like \fBSRCS, OBJS\fR, and \fBHDRS\fR.  These describe
the files needed
to recompile for that target machine, including both the machine-independent
files in the parent directory (the one containing \fBMakefile\fR) and
the machine-dependent files in the \fIx\fB.md\fR subdirectory.
.IP "\fB*.md/dependencies.mk\fP"
There is one of these files in each machine-dependent subdirectory.
\fBDependencies.mk\fR lists the header files used directly or
indirectly by each source file.  It is included by \fBMakefile\fR so that
\fBpmake\fR will do the appropriate recompilations when headers change.
\fBDependencies.mk\fR files are generated automatically by \fBmakedepend\fR.
The command ``pmake depend'' will run \fBmakedepend\fR
to regenerate \fBdependencies.mk\fR.  \fBMkmf\fR also issues
a ``pmake depend'' command whenever it runs.
.IP "\fIsysmakefile\fR"
There only a few different kinds of source directories in Sprite:
commands, libraries, kernel modules, etc (see ``HOW MKMF WORKS''
below).  For each of these types
of directories, there is one file of \fBpmake\fR commands that contains
all of the ``real stuff'' that controls recompilation, installing,
etc.  \fBMakefile\fR sets the variable \fBSYSMAKEFILE\fR to hold the name
of this file, and under normal conditions \fBMakefile\fR will
include the sysmakefile whenever \fBpmake\fR is invoked (see
``PERSONALIZATION'' below for exceptions to this rule).
The sysmakefiles use the variables and dependencies set up by \fBMakefile\fR,
\fBmd.mk\fR, and \fBdependencies.mk\fR.
The sysmakefiles are all stored in \fB/sprite/lib/pmake\fR.
.IP "\fIutility makefiles\fR"
There is a collection of small makefiles in the directory
\fB/sprite/lib/pmake\fR, which are include by sysmakefiles for
operations that are shared by many sysmakefiles.

.SH "STANDARD TARGETS"
.LP
Several standard \fBpmake\fR targets are available in any directory managed
by \fBmkmf\fR:
.TP 14
\fIdefault\fR
If you type \fBpmake\fR with no arguments, then the default target
just recompiles the program or library in this directory.  Compiled
files are placed in the .\fBmd\fR subdirectory for the current target machine
(see below for more information on target machines).
.TP 14
\fBclean\fR
Remove any files that can be regenerated automatically by \fBpmake\fR.
This frees up space on disk and forces a complete recompilation the
next time \fBpmake\fR is invoked.
.TP 14
\fBtidy\fR
Remove any files that can be regenerated automatically by \fBpmake\fR,
except the executable produced for a command.
This frees up space on disk and forces a complete recompilation the
next time \fBpmake\fR is invoked, but it leaves around the unstripped
executable for debugging purposes.
.TP 14
\fBdebug\fR
Valid for libraries only.  Generate a version of the library with
debugging symbols.  The default for libraries is to compile without
debugging information
.TP 14
\fBdepend\fR
Regenerate the \fBdependencies.mk\fR file in the \fB.md\fR subdirectory for
the current target machine.  This target should be re-made when source
files are created or deleted, or when header file usage has changed.
.TP 14
\fBinstall\fR
Recompiles the information in this directory and installs it in its
official system location, so that it can be used by other people.
For commands, this means copying the binary of the command to the
appropriate system command directory and saving the old installed
version of the command in a backup directory.  For libraries, it means
copying the library's .\fBa\fR file to the relevant library directory,
and also installing the library's header files and lint library.
.TP 14
\fBinstalldebug\fR
Valid for libraries only.  Install the version of the library with
debugging symbols.
.TP 14
\fBinstallhdrs\fR
This target is only available in library and header directories.  It
installs the public header files for the module in the appropriate system
header directory.  \fBMkmf\fR decides
which header files are public and which are private based on the files'
names.  In order to be public, the first letters of a \fB.h\fR file
must be the same as the name of the directory, and the string \fBInt\fR
must not appear in the file's name.  Thus, in the library \fBsx\fR
the file \fBsx.h\fR is public, whereas the files \fBsxInt.h\fR and
\fBfoo.h\fR are treated as private.
.TP 14
\fBinstalllint\fR
This target is only available in library directories.  It generates
a lint library file for the contents of this module and installs it
in the system lint library.
.TP 14
\fBinstallprofile\fR
This target is only available in library directories.  It installs
the version of the library that has been compiled for profiling.
.TP 14
\fBlint\fR
Run lint on this program/library and the other programs and libraries
it uses.  Output is placed in the file \fBlint\fR in the \fB.md\fR subdirectory
for the current machine.
.TP 14
\fBmkmf\fR
Run \fBmkmf\fR to regenerate the Makefile for this directory.   This target is
particularly useful in top-level directories with many children,
since it will run \fBmkmf\fR recursively in
each of the subdirectories.
.TP 14
\fBnewtm\fR
Set things up to compile for a new type of target machine (which
must be specified
explicitly using the \fBTM\fR variable).  This includes creating a \fB.TM\fR
subdirectory and re-running \fBmkmf\fR.
.TP 14
\fBprofile\fR
Compile a profiled version of the command or library.
.TP 14
\fBtags\fR
Generate a \fBtags\fR file in this directory that describes all the
information in all of the source files for this program or library,
including both the machine-independent sources and the machine-dependent
sources for all target machines.

.SH "TARGET MACHINES"
.LP
The above targets all apply to the ``current target machine'', which
is the value of the \fBTM\fR variable in \fBMakefile\fR.  If you wish to
compile for a different target machine, you can specify an explicit
value of the \fBTM\fR variable on the \fBpmake\fR command line, such as
.IP
\fBpmake\ \ TM=sun2\fR
.LP
or
.IP
\fBpmake\ \ install\ \ TM=sun3\fR
.LP
There are also four other ways you can specify target machines
as part of \fBpmake\fR targets:
.TP 14
\fItm\fR
If you specify a target machine as a \fBpmake\fR target, such as
\fBpmake sun2\fR, then the default target will be made for that
particular machine
.TP 14
\fBall\fR
The \fBall\fR target causes the default target to be made for all
target machines currently known for this directory.
.TP 14
\fItarget tm\fR
If you add a machine name as a suffix to one of the standard targets,
e.g., \fBpmake installsun2\fR or \fBpmake lintsun3\fR, the result
is equivalent to specifying the \fBTM\fR variable:  the target is
re-made for the given machine instead of the default machine.
.TP 14
\fItarget\fBall\fR
If you add the \fBall\fR suffix to a target, e.g. \fBpmake installall\fR,
then \fItarget\fR will be re-made for all known target machines.
.LP
The list of known target machines is given by the \fBMACHINES\fR
variable specified in \fBMakefile\fR.  This variable is set from the names
of \fB.md\fR subdirectories at the time \fBmkmf\fR is run.  To add a new target
machine, \fBfoo\fR for example, create a subdirectory \fBfoo.md\fR
and then re-run \fBmkmf\fR.

.SH "ADDITIONAL PMAKE VARIABLES"
.LP
There are a few variable names that \fBmkmf\fR reserves exclusively
for your use, as a way of controlling various things.  The makefiles
generated by \fBmkmf\fR will use these variables, if you set them on a
\fBpmake\fR command line:
.TP 14
\fBNOBACKUP\fR
Normally, when a command is installed the previous version of the
command is saved in a backup directory.  If you set the \fBNOBACKUP\fR
variable to any value, then no backup copy will be saved.
.TP 14
\fBBACKUPAGE\fR
If NOBACKUP is not defined, then normally, a backup overwrites a
previous backup only if the file being backed up is sufficiently old
to be deemed stable (run \fBupdate -help\fR for information about the
default age).  BACKUPAGE, if set, overrides the default age used for
this purpose.
.TP 14
\fBXAFLAGS\fR
Extra flags that will be used in all assembler invocations, in addition
to the standard ones set up by the makefiles.
.TP 14
\fBXCFLAGS\fR
Extra flags that will be used in all C compilations, in addition
to the standard ones set up by the makefiles.
.LP
In addition to the variables above, you can also override other variables
defined in the makefiles.  See "LOCAL.MK VARIABLES" below.

.SH "PERSONALIZATION"
.LP
The makefiles generated by \fBmkmf\fR won't always do the right thing
without additional program-specific information.
For example, a particular program may need to
use additional libraries besides the C library, or it may need
particular compiler switches, or certain files may need special
processing during compilation.  There are six ways to personalize
the information in a particular directory, each of which is
invoked by creating a file with a particular name:
.TP 14
\fBkernel.mk\fR
This file can be used to create personalized Sprite kernels.
\fBMakefile\fRs in kernel module directories will check for the
existence of a \fBkernel.mk\fR file in your home directory.
If the file exists it will be included prior to including any other
files.
The \fBkernel.mk\fR is intended modify the behavior of a sysmakefile
for
a kernel module,
not to replace it.
In this respect a \fBkernel.mk\fR file is different from a \fBlocal.mk\fR file.
.TP 14
\fBlocal.mk\fR
This is the simplest and most common form of personalization.
\fBMakefile\fR checks for the existence of \fBlocal.mk\fR;  if it
exists, then \fBMakefile\fR includes it instead of the sysmakefile.
Usually \fBlocal.mk\fR contains a few \fBpmake\fR commands, then it
includes the sysmakefile (whose name is passed in the variable
SYSMAKEFILE), then it issues a few more \fBpmake\fR
commands.  See "LOCAL.MK EXAMPLES" below.
.TP 14
\fBMakefile.sed\fR
If \fBMakefile.sed\fR exists when \fBmkmf\fR runs, then \fBmkmf\fR uses it as a Sed
script to modify \fBMakefile\fR.  If the \fB\-f\fR switch has been used
to specify a different makefile, say \fBfoo\fR, then \fBmkmf\fR looks for
\fBfoo.sed\fR.  In particular, you can place a file \fBmd.mk.sed\fR
in a machine-dependent subdirectory in order to modify the \fBmd.mk\fR
file.  Most things that you can do with a
\fBMakefile.sed\fR script you can also do in a \fBlocal.mk\fR file;
this feature is mostly a leftover from ancient times when the
\fBlocal.mk\fR facility didn't exist.
.TP 14
\fBMakefile.ex\fR
Similar to \fBMakefile.sed\fR, except \fBmkmf\fR uses it as an Ex script to
modify \fBMakefile\fR.
.TP 14
\fBMakefile.proto\fR
If this file exists when \fBmkmf\fR runs, then \fBmkmf\fR uses it as a
prototype makefile instead
of one from the \fBmkmf\fR library.  See ``HOW MKMF WORKS''
below for what this means.
.TP 14
\fBmkmf.local\fR
If this file exists, it must be a shell script.  It will be executed
by \fBmkmf\fR in place of the standard type-specific \fBmkmf\fR script that would
normally be executed to generate \fBMakefile\fR.  See ``HOW MKMF WORKS''
below for more information on this.
.LP
Finally, there is one other, even more radical,
way for you to control what's in your \fBMakefile\fR,
and that is to create your own \fBMakefile\fR from scratch
and make sure it
contains a line ``# No mkmf''.  \fBMkmf\fR will refuse to do anything
if it finds a \fBMakefile\fR with such a comment in it;
you can then put anything you like in the \fBMakefile\fR.
It's probably a bad idea (and unnecessary) for you ever to generate
a Makefile by hand in any Sprite system
directory, but if you do, be sure it has a ``# No mkmf'' line:
it is common practice to run \fBmkmf\fR indiscriminately on system directories,
and this will make sure your \fBMakefile\fR doesn't accidentally
get overwritten (actually, \fBmkmf\fR won't overwrite a makefile unless
it finds a line ``# Allow mkmf'' in it, but if it doesn't find a
``# No mkmf'' line then it will ask for permission to overwrite it).

.SH "HOW MKMF WORKS"
.LP
The \fBmkmf\fR program runs as a two-stage shell script.  The top-level
script is the \fBmkmf\fR program itself.  It does things that are
common to all uses of \fBmkmf\fR, such as checking for the ``# Allow mkmf''
line in your \fBMakefile\fR and running \fBpmake dependall\fR.
There are several second-level shell scripts, called \fItype-specific\fR
scripts.  Each one of these scripts is set up to handle a particular
kind of directory, such as those for libraries, programs, or directories
containing only header files.
The type-specific scripts correspond to the sysmakefiles:  for
each type, there is an \fBmkmf\fR script to generate its \fBMakefile\fR, a
prototype makefile that the script fills in, and a sysmakefile in
\fB/sprite/lib/pmake\fR that does most of the real work for making
things of that type.
The type-specific scripts and prototype makefiles are all
stored in \fB/sprite/lib/mkmf\fR with names like \fBmkmf.library\fR
and \fBMakefile.library\fR.
.LP
\fBMkmf\fR uses the file \fB/sprite/lib/mkmf/mkmf.map\fR to select
which type-specific script to use.  \fBMkmf.map\fR is an awk script
that performs pattern matching on the current directory to select
a type-specific script.  This file has already been set up to handle
most of the system areas, but if you add a major new area of programs
or libraries you'll probably have to add a new entry in \fBmkmf.map\fR.
If \fBmkmf\fR finds a script \fBmkmf.local\fR in the current directory, then
\fBmkmf\fR uses it instead of the one that would have been selected by
\fBmkmf.map\fR.  Similarly, if there is a file \fBMakefile.proto\fR
in the current directory, it is used instead of the default prototype
makefile.
.LP
You can reconfigure the way that \fBmkmf\fR works by placing a file \fB.mkmf\fR
in your home directory.  If this file exists, \fBmkmf\fR will source it as a
shell script just after doing its initialization.  You can use this
feature to set up a private map for yourself and change other internal
features of \fBmkmf\fR.  For more details on how this works, read the top-level
\fBmkmf\fR script.

.SH "CURRENT TYPES"
.LP
Although the list of available type-dependent scripts will probably
grow and change faster than this man page can be updated, here are the
types that were available as of the last time the man page was
updated.  To force \fBmkmf\fR to use a particular type (e.g.,
``library'' instead of ``command''), use either a \fBmkmf.local\fR or
a \fBMakefile.proto\fR, as described in ``HOW MKMF WORKS,'' above.
.TP 14
\fBcommand\fR
This type is for command directories where all of the files related
to the command are together in a single directory and its \fB.md\fR
subdirectories.  It is the default type used by \fBmkmf\fR for directories
not explicitly listed in \fBmkmf.map\fR.
\fBMakefile\fR will compile and link the command into
\fItm\fB.md/\fIname\fR, where \fItm\fR is the name of a target machine
and \fIname\fR is the name of the directory containing \fBMakefile\fR
(the directory name and command name are assumed to be the same).
\fBMakefile\fR will install the command into the appropriate system
directory (see the \fBmkmf\fR scripts for details on where this is).
During the conversion of Sprite to the new C library, this type of
directory is actually \fBcommand2\fR, but it will revert to \fBcommand\fR
when the conversion is finished.
.TP 14
\fBbigcmd\fR
This type is for commands whose source files have been partitioned into
multiple subdirectories, with one \fBMakefile\fR for each subdirectory.
The \fBMakefile\fRs in the subdirectories are of type \fBbigcmd\fR,
and the \fBMakefile\fR of the parent is of type \fBbigcmdtop\fR.
Each \fBbigcmd\fR subdirectory contains \fItm\fB.md\fR subdirectories,
which contain object files compiled from that subdirectory plus a file
\fBlinked.o\fR, which consists of all the object files from that
subdirectory linked together.
.TP 14
\fBbigcmdtop\fR
This type is used for a command source directory that contains one
or more subdirectories of type \fBbigcmd\fR.  The \fBMakefile\fR in this
directory will cause all the children directories to be re-made,
plus it will regenerate the file \fItm\fB.md/\fIname\fR, where \fItm\fR
is the name of a target machine and \fIname\fR is the name of the
\fBbigcmdtop\fR directory.  A special target \fBquick\fR is also available
in \fBbigcmdtop\fR directories:  it will relink \fItm\fB.md/\fIname\fR
using the existing \fBlinked.o\fR files from the children, without
passing through all the subdirectories to remake there.
.TP 14
\fBlibrary\fR
This type is for directories containing all of the files related to
a particular library.  \fBMakefile\fR will compile all the files in
the directory and assemble them into an archive file named
\fItm\fB.md/lib\fIname\fB.a, where \fItm\fR is the name of a target machine
and \fIname\fR is the name of the directory containing \fBMakefile\fR
(the directory name and library name are assumed to be the same).
\fBMakefile\fR will install the library and its headers and lint library.
.TP 14
\fBbiglib\fR
This type is for libraries with many source files, such as the C
library.  The library's sources are assumed to be split over many
subdirectories, with one \fBMakefile\fR for each subdirectory.  The
\fBMakefile\fRs in the subdirectories are of type \fBbiglib\fR, and
the \fBMakefile\fR of the parent is of type \fBbiglibtop\fR.  Compiled
files will be archived together into the
file \fB../\fItm\fB.md/lib\fIname\fB.a\fR (relative to the subdirectories
containing the \fBbiglib\fR \fBMakefile\fRs), where \fItm\fR is the name
of a target machine and \fIname\fR is the name of the top-level
directory (the directory containing the \fBbiglib\fR directories is
assumed to have the same name as the overall library).
.TP 14
\fBbigligtop\fR
This is the type of a directory that contains one or more \fBbiglib\fR
subdirectories.  The \fBMakefile\fR in this directory will pass most
of the standard targets along to its children directories.  The
installation targets (such as \fBinstall\fR and \fBinstalllint\fR)
should be invoked in this directory.  A special target \fBinstallquick\fR
is also available in \fBbiglibtop\fR directories:  it will install
the standard version of the library without cycling through all of
the subdirectories to give each of them a chance to recompile.
.TP 14
\fBkernel\fR
This type is used in the directories that hold the major modules of
the Sprite kernel.
.TP 14
\fBhdrs\fR
This type is used for directories that hold nothing but ``.h'' files
for the standard library.  The only thing you can do with \fBpmake\fR is to
install the header files;  the default target does this, as does
\fBpmake install\fR.  In addition, \fBpmake recursive\fR will install
header files in this directory and all of its subdirectories (this is
only useful for header directories that contain more header directories
as subdirectories).
.TP 14
\fBtop\fR
This is a general-purpose type for directories that don't
have anything interesting in themselves, but have child directories
that do contain interesting things.  When \fBpmake\fR is run in such
a directory, the \fBMakefile\fR will simply pass all the standard targets
down to each of its child directories in turn.  This type of \fBMakefile\fR
is used, for example, in the top-level directory of a \fBbiglib\fR
tree, or in a top-level commands directory, each of whose children
is of type \fBcommand\fR.

.SH "LOCAL.MK VARIABLES"
.PP
The following list describes some of the variables that you may wish
to use, augment (using ``+=''), or override in \fBlocal.mk\fR files.
This is just a list of the most commonly-used variables.  For other
possibilities, read the makefiles.
.TP 18
\fBAFLAGS\fR
Flags passed to the assembler.  You may wish to augment this in \fBlocal.mk\fR.
.TP 18
\fBCFLAGS\fR
Flags passed to the C compiler.  You may wish to augment this in
\fBlocal.mk\fR, for example to define certain compiler switches.
Or, you can override the value in \fBMakefile\fR with something
completely different.
.TP 18
\fBCLEANOBJS\fR
A list of object files and other things to delete as part of
\fBpmake clean\fR or \fBpmake tidy\fR.
.TP 18
\fBHDRS\fR
A list of all the locally-defined ``.h'' files (both machine-dependent
and machine-independent) used to compile this module.
.TP 18
\fBINSTALLDIR\fR
The base directory in which a program gets installed.  \fBMkmf\fR will add
a machine-dependent suffix onto this, depending on the particular
machine being compiled for (see the makefiles for more details on this).
.TP 18
\fBINSTALLFLAGS\fR
Flags passed to \fBupdate\fR when the module is installed.  You may wish
to add extra flags, like \fB\-m 4755\fR to make a program set-user-id.
.TP 18
\fBOBJS\fR
A list of all the object files used to link together this module.
These files should always be in a machine-dependent directory.
.TP 18
\fBSRCS\fR
A list of all the source files (both machine-dependent and
machine-independent) that comprise the module's version for the
current target machine.
.TP 18
\fBSUBDIRS\fR
A list of all the subdirectories of this directory, except those of
type \fItm\fB.md\fR).  Is usually only
available in top-level Makefiles, like those in directories of type
\fBtop\fR, \fBbigcmdtop\fR, or \fBbiglibtop\fR.  This variable determines
where to invoke recursive sub-makes.
.TP 18
\fBTM\fR
The name of the current target machine.  Normally this is specified on
the command line or defaulted in \fBMakefile\fR, so you shouldn't
modify it.

.SH "LOCAL.MK EXAMPLES"
.PP
The normal structure for a \fBlocal.mk\fR file is for it to set
up or modify a few variables, include the sysmakefile, and then
add new targets or extend targets defined by the sysmakefile.
For example, here is a simple \fBlocal.mk\fR that defines some
additional compiler variables (by adding to \fBCFLAGS\fR) and
uses an extra library:
.DS
\fBCFLAGS    += -DNAME=testProg
LIBS        += -lm\ \ -X11
#include    <$(SYSMAKEFILE)>\fR
.DE
.LP
Or, below is a \fBlocal.mk\fR that generates an additional C file from
a template.  Since the file may not have existed when \fBmkmf\fR was run, it
must be added to the \fBSRCS\fR and \fBOBJS\fR variables generated by
\fBmkmf\fR.  In addition, when this program is installed (using the \fBupdate\fR
command), it is marked at set-user-id (mode 4755):
.DS
\fBSRCS            += auto.c
OBJS            += $(TM).md/auto.o
INSTALLFLAGS    += -m 4755

#include        <$(SYSMAKEFILE)>

auto.c: template prog
    prog template > auto.c\fR
.DE
.LP
The reason for adding new targets after including the sysmakefile
is to allow the sysmakefile to define the first target, which is the
default that will be made if \fBpmake\fR is invoked with no arguments.  If,
on the other hand, you want to change the default target, then you
can define the default target before including the sysmakefile.
.LP
As a third example, consider a program that uses non-standard header
files.  It would have a local.mk that looks something like
.DS
\fB#include    <$(SYSMAKEFILE)>

\&.PATH.h :    /sprite/lib/include.special
.DE
.LP
Notice that the
.B .PATH.h
line comes after the sysmakefile is included.

.SH "SEE ALSO"
pmake, sed, ex

.SH KEYWORDS
make, Makefile, prototype
@


1.10
log
@Add a local.mk example for using .PATH.h.
@
text
@d1 1
a1 1
' $Header: /sprite/src/cmds/mkmf.prog/RCS/mkmf.man,v 1.9 90/09/21 16:50:41 kupfer Exp Locker: kupfer $ SPRITE (Berkeley)
d564 1
d594 1
@


1.9
log
@Add a note to the CURRENT TYPES section about how to force mkmf to use
a particular type.
@
text
@d1 1
a1 1
' $Header: /sprite/src/cmds/mkmf.prog/RCS/mkmf.man,v 1.8 90/02/27 17:46:06 douglis Exp Locker: kupfer $ SPRITE (Berkeley)
d585 11
@


1.8
log
@documented BACKUPAGE
@
text
@d1 1
a1 1
' $Header: /sprite/src/cmds/mkmf.prog/RCS/mkmf.man,v 1.7 89/05/22 12:30:14 jhh Exp Locker: douglis $ SPRITE (Berkeley)
d400 5
a404 3
grow and change faster than this man page can be updated, here are
the types that were available as of the last time the man page was
updated:
@


1.7
log
@can now do -mtm
@
text
@d1 1
a1 1
' $Header: /a/newcmds/mkmf.prog/RCS/mkmf.man,v 1.6 89/04/03 22:19:32 douglis Exp $ SPRITE (Berkeley)
d264 8
a271 1
variable to any value, then no backup copy will be saved.
@


1.6
log
@added tidy in the right place, under "standard targets"
@
text
@d1 1
a1 1
' $Header: /a/newcmds/mkmf.prog/RCS/mkmf.man,v 1.4 89/04/03 22:16:36 douglis Exp Locker: douglis $ SPRITE (Berkeley)
d9 1
d20 1
a20 1
.IP "\fB\-m \fImachineType\fR"
@


1.5
log
@mention "tidy" along with "clean".
@
text
@d136 7
@


1.4
log
@JHH added the kernel.mk personalization.
@
text
@d1 1
a1 1
' $Header: /a/newcmds/mkmf.prog/RCS/mkmf.man,v 1.3 88/12/30 09:56:12 ouster Exp $ SPRITE (Berkeley)
d498 1
a498 1
\fBpmake clean\fR.
@


1.3
log
@More format upgrades.
@
text
@d1 1
a1 1
' $Header: /a/newcmds/mkmf.prog/RCS/mkmf.man,v 1.2 88/12/28 12:05:25 ouster Exp Locker: ouster $ SPRITE (Berkeley)
d8 1
a8 1
\fBmkmf\fR [\fB\-f \fImakefile\fR] [\fB\-x\fR]
d19 4
d276 1
a276 1
processing during compilation.  There are five ways to personalize
d279 12
@


1.2
log
@Upgrade to new official man page format.
@
text
@d1 1
a1 1
' $Header: /a/newcmds/mkmf.prog/RCS/mkmf.man,v 1.1 88/12/28 11:43:58 ouster Exp Locker: ouster $ SPRITE (Berkeley)
d8 1
a8 1
\fBmkmf\fR [\fB-f \fImakefile\fR] [\fB-x\fR]
d10 1
a10 1
.IP "\fB-f \fImakefile\fR"
d15 2
a16 2
.IP "\fB-x\fR"
Turns on echo-ing so that all the commands in the Mkmf scripts
d18 1
a18 1
debugging Mkmf scripts.
d23 1
a23 1
Mkmf generates a \fBMakefile\fR for the current working directory.  It
d25 1
a25 1
subdirectories of the current directory.  Mkmf can generate
d28 2
a29 2
Mkmf manages all of the directories holding Sprite system code.
In normal use, all you should have to do is type "mkmf";  Mkmf
d33 5
a37 5
Pmake to recompile in the directory, install, and so on.  The files
produced by Mkmf will only work with Pmake, not with the original
UNIX version of Make (but in Sprite "make" is a symbolic link to
"pmake").  This man page assumes that you are familiar with Pmake;  if
not, you should read the Pmake tutorial.
d39 1
a39 1
Warning:  there is also a UNIX program called Mkmf;  although its
d42 2
a43 2
Normally, you should re-run Mkmf in a directory whenever you add or delete
source files.  When Mkmf runs, it assumes that
d48 1
a48 1
put them in a subdirectory where Mkmf won't see them.
d52 1
a52 1
The makefile structure that Mkmf generates is a bit complicated,
d58 1
a58 1
there are five kinds of Pmake-related files:
d60 2
a61 2
This is the main file generated by Mkmf, but it is short and
does relatively little.  It sets up several Pmake
d65 1
a65 1
which contain most of the useful Pmake-related information.
d82 1
a82 1
file \fBmd.mk\fR, generated automatically by Mkmf.
d93 4
a96 4
Pmake will do the appropriate recompilations when headers change.
\fBDependencies.mk\fR files are generated automatically by Makedepend.
The command ``pmake depend'' will run Makedepend
to regenerate \fBdependencies.mk\fR.  Mkmf also issues
d102 1
a102 1
of directories, there is one file of Pmake commands that contains
d106 1
a106 1
include the sysmakefile whenever Pmake is invoked (see
d118 2
a119 2
Several standard Pmake targets are available in any directory managed
by Mkmf:
d128 1
a128 1
Remove any files that can be regenerated automatically by Pmake.
d130 1
a130 1
next time Pmake is invoked.
d158 1
a158 1
header directory.  Mkmf decides
d181 1
a181 1
Run Mkmf to regenerate the Makefile for this directory.   This target is
d183 1
a183 1
since it will run Mkmf recursively in
d190 1
a190 1
subdirectory and re-running Mkmf.
d206 1
a206 1
value of the \fBTM\fR variable on the Pmake command line, such as
d215 1
a215 1
as part of Pmake targets:
d218 1
a218 1
If you specify a target machine as a Pmake target, such as
d238 1
a238 1
of \fB.md\fR subdirectories at the time Mkmf is run.  To add a new target
d240 1
a240 1
and then re-run Mkmf.
d244 1
a244 1
There are a few variable names that Mkmf reserves exclusively
d246 2
a247 2
generated by Mkmf will use these variables, if you set them on a
Pmake command line:
d267 1
a267 1
The makefiles generated by Mkmf won't always do the right thing
d280 1
a280 1
Usually \fBlocal.mk\fR contains a few Pmake commands, then it
d282 1
a282 1
SYSMAKEFILE), then it issues a few more Pmake
d286 3
a288 3
If \fBMakefile.sed\fR exists when Mkmf runs, then Mkmf uses it as a Sed
script to modify \fBMakefile\fR.  If the \fB-f\fR switch has been used
to specify a different makefile, say \fBfoo\fR, then Mkmf looks for
d297 1
a297 1
Similar to \fBMakefile.sed\fR, except Mkmf uses it as an Ex script to
d301 1
a301 1
If this file exists when Mkmf runs, then Mkmf uses it as a
d303 1
a303 1
of one from the Mkmf library.  See ``HOW MKMF WORKS''
d308 1
a308 1
by Mkmf in place of the standard type-specific Mkmf script that would
d316 1
a316 1
contains a line ``# No mkmf''.  Mkmf will refuse to do anything
d322 1
a322 1
it is common practice to run Mkmf indiscriminately on system directories,
d324 1
a324 1
get overwritten (actually, Mkmf won't overwrite a makefile unless
d330 3
a332 3
The Mkmf program runs as a two-stage shell script.  The top-level
script is the Mkmf program itself.  It does things that are
common to all uses of Mkmf, such as checking for the ``# Allow mkmf''
d339 1
a339 1
each type, there is an Mkmf script to generate its \fBMakefile\fR, a
d347 1
a347 1
Mkmf uses the file \fB/sprite/lib/mkmf/mkmf.map\fR to select
d353 2
a354 2
If Mkmf finds a script \fBmkmf.local\fR in the current directory, then
Mkmf uses it instead of the one that would have been selected by
d359 2
a360 2
You can reconfigure the way that Mkmf works by placing a file \fB.mkmf\fR
in your home directory.  If this file exists, Mkmf will source it as a
d363 2
a364 2
features of Mkmf.  For more details on how this works, read the top-level
Mkmf script.
d376 1
a376 1
subdirectories.  It is the default type used by Mkmf for directories
d383 1
a383 1
directory (see the Mkmf scripts for details on where this is).
d447 1
a447 1
for the standard library.  The only thing you can do with Pmake is to
d457 1
a457 1
that do contain interesting things.  When Pmake is run in such
d489 1
a489 1
The base directory in which a program gets installed.  Mkmf will add
d495 1
a495 1
to add extra flags, like \fB-m 4755\fR to make a program set-user-id.
d532 1
a532 1
a template.  Since the file may not have existed when Mkmf was run, it
d534 1
a534 1
Mkmf.  In addition, when this program is installed (using the \fBupdate\fR
d549 1
a549 1
default that will be made if Pmake is invoked with no arguments.  If,
@


1.1
log
@Initial revision
@
text
@d1 3
a3 2
' $Header: /sprite/doc/ref/cmds/RCS/mkmf,v 1.8 88/12/04 14:51:56 ouster Exp $ SPRITE (Berkeley)
.TH mkmf prog
d5 1
a5 1
.NA
d7 1
a7 1
.SY
@